REST Architectural Style

REST is an architectural style that Roy Fielding introduced in his thesis Architectural Styles and the Design of Network-based Software Architectures. I found this paper interesting for a couple of reasons:

• Most of the paper is not actually about REST. It is about software architecture, and it introduces a framework for selecting the correct architectural style for your network based system. This framework is a methodological approach for designing systems and is a useful addition to your tool belt.
• It also contains an interesting history lesson about the early www and its requirements, mistakes, and learning from those mistakes in order to architect the modern web.
• It has a lot less to do with APIs than I thought.

These are a collection of my notes and thoughts while I was studying the topic. It's not meant to be a comprehensive review of the topic (although I do hope to add more content around some parts I handwaved over), but an aid in building some intuition. Hopefully they will help digest what REST is, and inspire you to read Roy Fielding's dissertation.

I'll try to describe REST a few different ways. I'll start off simple and then try to describe it by introducing some vocaubulary Fielding uses in his dissertation.

• If you are part of a software system that involves multiple organizations (this can also be multiple organizations within a single company), it is very difficult to decide how to pass data between the different components of the system. Especially so when those systems cross organizational boundaries. The uniform interface allows you to standardize on messages between the components of your system rather than the data.

  For example, consider HTML forms. HTML forms are hypermedia that describes (in the message) what data should be sent between two systems, and how that data should be sent. As long as the systems implement the contract described through the message, the service is decoupled from the implementation of the service and decoupled from details such as internal data models used throughout the system.

• Another benefit of REST is HATEOS (hypermedia as the engine of application state). This means that the hypermedia links that exist in a message describe the state of the system, and the links change as the state of the system changes. You can create a client that is late binded¹ to the links in the message, which guide the client through what we are providing as a service. Consider how valuable this is if you have multiple independently deployed clients (websites, phone apps, desktop apps, etc) that consume the same service. If they understand the uniform interface and are late binded to the links in the message, the service can change how it "guides" the clients dynamically.

  Think of a message as the current state in a state machine, and a hypermedia link as instructions on how to bring the system to a new state. Clients are late binded to the transitions that exist in a message, which can change and be updated independently of the clients.

Every application has a set of requirements, and each architectural constraint induces both positive and negative properties on your system. Your goal is to create a set of properties that fulfils the requirements of your system.

Read Roy Fielding's dissertation for more information.